dxp-ux
POST Prepay-Topup Balance (TMF-654)
[POST]
The createTopupBalance API provides 2 below features,
#createTopupBalance#: allows the customer to top up their account with a mobile number that they have specified (MSISDN) or subscriptionId.
#Retrive Tax Info#: API returns the estimated tax amount before making the top-up if we call API with field reason = TAX.
Please find sample requests and responses for both scenarios below.
This API is available for LCPR.
URL
http://[localhost]:[port]/dxp-ux/v1/{businessId}/topupBalanceURL PARAMS
| name | type | description | required |
|---|---|---|---|
| businessId | string | 2 letter ISO 3166 country code (TT, BB, JM, PA, PR etc.) identifying the business unit. | Y |
Header
| name | value | description | required |
|---|---|---|---|
| client_id | string | The client_id identifying the channel. Minimum characters: 5 | Y |
| client_secret | string | Password associated with the client_id. Minimum characters: 5 | Y |
| lob | string | The Line of Business Identifier currently available are: FIXED PREPAID POSTPAID | N |
| channeId | string | Channel to business: Allowed value: "APP" | Y |
| X-Correlation-ID | string | Identifier that correlates HTTP request between a client and server. Any identification model (UUDI, checksum, etc.) can be used, as long as it is a unique value to differentiate a transaction. | Y |
| targetSystem | String | This describes the target system. “Matrixx” is in scope. | Y |
REQUEST BODY FOR TAX_INFORMATION
Note - 1) The possiable values of reason attributes are "TAX/ESTIMATE/TAX ESTIMATE"
2) No need to pass valid voucher(one time code/nonce) code, it will accept any dumy value.
REQUEST BODY FOR TAX_INFORMATION using MSISDN
{
"amount": {
"amount": 100,
"units": "USD"
},
"reason": "TAX ESTIMATE",
"voucher": "A",
"product": [
{
"id": "01",
"name": "RechargeOffer",
"@type": "Offer"
}
],
"partyAccount": {
"id": "9347455272",
"@type": "MSISDN"
}
}Definitions
Each of the request parameters is detailed for Tax information request body
| Field Name | M/O | Description | DataType |
|---|---|---|---|
| amount | M | object | Quantity |
| amount.amount | M | Unit number, the amount that you are doing recharge to customer | number |
| amount.units | O | Currency (ISO4217 norm uses 3 letters to define the currency) | string |
| Reason | M | The "reason" field it should be passed as (tax, estimate, tax estimate) and the voucher field is passed as null or random values, to obtain tax details before paying for the topup | string |
| voucher | M | Voucher is mandatory field we should have to any random value or null , to obtain tax details before paying for the topup, | string |
| product | M | A reference to the Product associated with this bucket | array |
| product.id | M | no significance required field in raml , but we are not passing any value we are passing as empty string | string |
| product.name | M | Name of the related entity,it is a product name recharge offer name ,it is hardcoded value | string |
| product.@type | M | it is a offer type , it is hardcoded value | string |
| partyAccount | M | object | string |
| partyAccount.id | M | Customer Mobile Number | string |
| partyAccount.type | M | Hard coded value "MSISDN" | string |
RESPONSE BODY FOR TAX_INFORMATION
{
"status": "Success",
"amount": {
"amount": 100,
"units": "USD"
},
"voucher": "A",
"reason": "TAX ESTIMATE",
"product": [
{
"id": "0",
"name": "RechargeOffer",
"@type": "Offer"
}
],
"validFor": {
"endDateTime": "65535-12-31T23:59:59.999999Z",
"startDateTime": "2022-08-30T09:07:14.000Z"
},
"bucket": {
"id": "1",
"name": "Prepaid Balance"
},
"impactedBucket": [
{
"amountAfter": 111.5,
"name": "Total Amount",
"item": [
{
"amount": 10.5,
"name": "STATE SALES TAX"
},
{
"amount": 1.0,
"name": "CITY SALES TAX"
}
]
}
],
"partyAccount": {
"id": "9347455272",
"@type": "MSISDN"
}
}Definitions
Each of the response parameters is detailed for Tax information response body
| Field Name | DataType | Description | M/O |
|---|---|---|---|
| status | string | Valid values for the Action Status Type | N |
| amount | Quantity | object | N |
| amount.amount | number | Unit number, the amount that you are doing recharge to customer | N |
| amount.units | string | Currency (ISO4217 norm uses 3 letters to define the currency) | N |
| Reason | The "reason" field it should have to passed as (tax, estimate, tax estimate) and the voucher field is passed as null or random values, to obtain tax details before paying for the topup | N | |
| voucher | string | Voucher is mandatory field we should have to any random value or null , to obtain tax details before paying for the topup, | N |
| validFor | object | A period of time, either as a deadline (endDateTime only) a startDateTime only, or both | N |
| validFor.startDateTime | datetime | Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end | N |
| validFor.endDateTime | datetime | End of the time period, using IETC-RFC-3339 format | N |
| bucket | object | link to the resource that holds bucket information | N |
| bucket.id | string | unique identifier | N |
| bucket.name | string | Name of the related entity. | N |
| impactedBucket | array | Tax information | N |
| amountAfter | string | The total amount that you are paying for topup with Tax includes | N |
| impactedBucket.name | string | Name of the impactedBucket. | N |
| impactedBucket.item | array | Array of items in impactedBucket. | N |
| impactedBucket.item.amount | integer | Amount paying for STATE SALES TAX and CITY SALES TAX | N |
| impactedBucket.item.name | string | Name related to STATE SALES TAX and CITY SALES TAX | N |
| product | array | A reference to the Product associated with this bucket | N |
| product.id | string | no significance required field in raml , but we are not passing any value we are passing as empty string | N |
| product.name | string | Name of the related entity,it is a product name recharge offer name ,it is hardcoded value | N |
| product.@type | string | it is a offer type , it is hardcoded value | N |
| partyAccount | string | object | N |
| partyAccount.id | string | Customer Mobile Number | N |
| partyAccount.type | string | Hard coded value "MSISDN" | N |
REQUEST BODY FOR TAX_INFORMATION using subscriptionId
{
"amount": {
"amount": 100,
"units": "USD"
},
"reason": "TAX ESTIMATE",
"voucher": "A",
"product": [
{
"id": "01",
"name": "RechargeOffer",
"@type": "Offer"
}
],
"partyAccount": {
"id": "S-94537890",
"@type": "subscriptionId"
}
}Definitions
Each of the request parameters is detailed for Tax information request body
| Field Name | M/O | Description | DataType |
|---|---|---|---|
| amount | M | object | Quantity |
| amount.amount | M | Unit number, the amount that you are doing recharge to customer | number |
| amount.units | O | Currency (ISO4217 norm uses 3 letters to define the currency) | string |
| Reason | M | The "reason" field it should have to passed as (tax, estimate, tax estimate) and the voucher field is passed as null or random values, to obtain tax details before paying for the topup, | string |
| voucher | M | Voucher is mandatory field we should have to any random value or null , to obtain tax details before paying for the topup, | string |
| product | M | A reference to the Product associated with this bucket | array |
| product.id | M | no significance required field in raml , but we are not passing any value we are passing as empty string | string |
| product.name | M | Name of the related entity,it is a product name recharge offer name ,it is hardcoded value | string |
| product.@type | M | it is a offer type , it is hardcoded value | string |
| partyAccount | M | object | string |
| partyAccount.id | M | Customer subscriptionId | string |
| partyAccount.type | M | Hard coded value "subscriptionId" | string |
RESPONSE BODY FOR TAX_INFORMATION
{
"status": "Success",
"amount": {
"amount": 100,
"units": "USD"
},
"voucher": "A",
"reason": "TAX ESTIMATE",
"product": [
{
"id": "0",
"name": "RechargeOffer",
"@type": "Offer"
}
],
"validFor": {
"endDateTime": "65535-12-31T23:59:59.999999Z",
"startDateTime": "2022-08-30T09:07:14.000Z"
},
"bucket": {
"id": "1",
"name": "Prepaid Balance"
},
"impactedBucket": [
{
"amountAfter": 111.5,
"name": "Total Amount",
"item": [
{
"amount": 10.5,
"name": "STATE SALES TAX"
},
{
"amount": 1.0,
"name": "CITY SALES TAX"
}
]
}
],
"partyAccount": {
"id": "S-94537890",
"@type": "subscriptionId"
}
}Definitions
Each of the response parameters is detailed for Tax information response body
| Field Name | DataType | Description | M/O |
|---|---|---|---|
| status | string | Valid values for the Action Status Type | N |
| amount | Quantity | object | N |
| amount.amount | number | Unit number, the amount that you are doing recharge to customer | N |
| amount.units | string | Currency (ISO4217 norm uses 3 letters to define the currency) | N |
| Reason | The "reason" field it should have to passed as (tax, estimate, tax estimate) and the voucher field is passed as null or random values, to obtain tax details before paying for the topup, | N | |
| voucher | string | Voucher is mandatory field we should have to any random value or null , to obtain tax details before paying for the topup, | N |
| validFor | object | A period of time, either as a deadline (endDateTime only) a startDateTime only, or both | N |
| validFor.startDateTime | datetime | Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end | N |
| validFor.endDateTime | datetime | End of the time period, using IETC-RFC-3339 format | N |
| bucket | object | link to the resource that holds bucket information | N |
| bucket.id | string | unique identifier | N |
| bucket.name | string | Name of the related entity. | N |
| impactedBucket | array | Tax information | N |
| amountAfter | string | The total amount that you are paying for topup with Tax includes | N |
| impactedBucket.name | string | Name of the impactedBucket. | N |
| impactedBucket.item | array | Array of items in impactedBucket. | N |
| impactedBucket.item.amount | integer | Amount paying for STATE SALES TAX and CITY SALES TAX | N |
| impactedBucket.item.name | string | Name related to STATE SALES TAX and CITY SALES TAX | N |
| product | array | A reference to the Product associated with this bucket | N |
| product.id | string | no significance required field in raml , but we are not passing any value we are passing as empty string | N |
| product.name | string | Name of the related entity,it is a product name recharge offer name ,it is hardcoded value | N |
| product.@type | string | it is a offer type , it is hardcoded value | N |
| partyAccount | string | object | N |
| partyAccount.id | string | Customer subscriptionId | N |
| partyAccount.type | string | Hard coded value "subscriptionId" | N |
REQUEST BODY FOR TOPUP BALANCE
Note - 1) No need to pass reason attribute.
2) Expecting valid voucher (one time code/nonce) code for complete top-up balance.
{
"id": "123456",
"amount": {
"amount": 100,
"units": "USD"
},
"voucher": "fake-valid-nonce",
"product": [
{
"id": "01",
"name": "RechargeOffer",
"@type": "Offer"
}
],
"relatedParty": [
{
"id": "628935575",
"@type": "PaymentGatewayUserId"
},
{
"id": "0",
"@type": "PaymentGatewayId"
}
],
"partyAccount": {
"id": "9347455272",
"@type": "MSISDN"
}
}Definitions
Each of the request parameters is detailed.
| name | type | description | required |
|---|---|---|---|
| id | string | The unique order id used in the authorize or settlement request. This can be used to track the transaction and aids duplicate checking. | N |
| amount | Quantity | An amount in a given unit | Y |
| amount.amount | string | Top-Up Amount | Y |
| amount.units | string | Unit | N |
| product | array | A reference to the Product associated with this bucket, Consumer should pass as static values like in sample request payload. Note: As pr TMF-654 guidelines, There should be at least one product of '@type'=offer, | N |
| product.id | string | unique identifier | N |
| product.name | string | Name of the related entity. | N |
| product.@type | string | When sub-classing, this defines the sub-class Extensible name | N |
| partyAccount | object | PartyAccount reference. A party account is an arrangement that a party has with an enterprise that | Y |
| partyAccount.id | string | Either subscriber by ExternalID or associated device access number | Y |
| partyAccount.@type | string | When sub-classing, this defines the sub-class entity name of partyAccount, In this case either MSISDN/SubscriptionId | N |
| voucher | Nonce to use for authorization. Note - Either "PaymentMethodResourceId" or "voucher" only allow. Both should not allow After successful Payment, "BRAIN TREE" will send encrypted transaction code/one time code to DXP | Y* | |
| relatedParty | array | Used to provide information about any other entity with relation to the operation, Please refer below relatedParty Table for more details | Y |
| relatedParty.id | Unique identifier of a related entity. | Y |
relatedParty values
| relatedParty type | type | description | required |
|---|---|---|---|
| PaymentGatewayUserId | string | Identifier for the customer id on the payment gateway, "BRAIN TREE". | Y |
| PaymentGatewayId | string | Identifier for the specific payment gateway. If not supplied, the default payment gateway will be used.", | Y |
RESPONSE BODY FOR TOPUP BALANCE
{
"id": "123456",
"confirmationDate": "2022-11-08T08:24:35.000Z",
"status": "Approved",
"amount": {
"amount": 100,
"units": "USD"
},
"voucher": "fake-valid-nonce",
"product": [
{
"id": "0",
"name": "RechargeOffer",
"@type": "Offer"
}
],
"validFor": {
"endDateTime": "65535-12-31T23:59:59.999999Z",
"startDateTime": "2022-08-30T09:07:14.000Z"
},
"relatedParty": [
{
"id": "628935575",
"@type": "PaymentGatewayUserId"
},
{
"id": "0",
"@type": "PaymentGatewayId"
},
{
"id": "70",
"@type": "PaymentResourceIdRef"
}
],
"bucket": {
"id": "1",
"name": "Prepaid Balance"
},
"impactedBucket": [
{
"amountAfter": 111.5,
"name": "Total Amount",
"item": [
{
"amount": 10.5,
"name": "STATE SALES TAX"
},
{
"amount": 1.0,
"name": "CITY SALES TAX"
}
]
}
],
"partyAccount": {
"id": "9347455272",
"@type": "MSISDN"
}
}Definitions
Each of the response parameters is detailed for Topup Balance response body
| Field Name | DataType | Description | M/O |
|---|---|---|---|
| id | string | The unique id used in the authorise or settlement request. This can be used to track the transaction and aids duplicate checking | N |
| status | string | Valid values for the Action Status Type | N |
| confirmationDate | datetime | when the deduction was confirmed in the server | N |
| amount | Quantity | object | N |
| amount.amount | number | Unit number, the amount that you are doing recharge to customer | N |
| amount.units | string | Currency (ISO4217 norm uses 3 letters to define the currency) | N |
| voucher | string | After successful Payment, "BRAIN TREE" will send encrypted transaction code/one time code | N |
| validFor | object | A period of time, either as a deadline (endDateTime only) a startDateTime only, or both | N |
| validFor.startDateTime | datetime | Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end | N |
| validFor.endDateTime | datetime | End of the time period, using IETC-RFC-3339 format | N |
| bucket | object | link to the resource that holds bucket information | N |
| bucket.id | string | unique identifier | N |
| bucket.name | string | Name of the related entity. Identify the account type example :Prepaid | N |
| impactedBucket | array | Tax information | N |
| amountAfter | string | The total amount that you are paying for topup with Tax includes | N |
| impactedBucket.name | string | Name of the impactedBucket. | N |
| impactedBucket.item | array | Array of items in impactedBucket. | N |
| impactedBucket.item.amount | integer | Amount paying for STATE SALES TAX and CITY SALES TAX | N |
| impactedBucket.item.name | string | Name related to STATE SALES TAX and CITY SALES TAX | N |
| product | array | A reference to the Product associated with this bucket | N |
| product.id | string | no significance required field in raml , but we are not passing any value we are passing as empty string | N |
| product.name | string | Name of the related entity,it is a product name recharge offer name ,it is hardcoded value | N |
| product.@type | string | It represents is a offer type , it is hardcoded value | N |
| partyAccount | string | object | N |
| partyAccount.id | string | Customer Mobile Number | N |
| partyAccount.type | string | Hard coded value "MSISDN" | N |
relatedParty
| name | type | description | required |
|---|---|---|---|
| PaymentGatewayUserId | string | Payment gate way user id; will get this info from "BRAIN TREE". | N |
| PaymentGatewayId | string | Identifier for the specific payment gateway. If not supplied, the default payment gateway will be used here default gateway is "BRAIN TREE". | N |
| PaymentResourceIdRef | string | Payment resource id | N |
Possible Error Scenarios: :
IF WE ARE PASSING INVALID (MSISDN) NUMBER IN REQUEST BODY
{
"errors": [
{
"code": 400,
"message": "MATRIXX:POST_TOPUP_BALANCE",
"description": "11 | Subscriber not found (AccessNumber=709565949)"
}
]
}IF WE ARE PASSING INVALID VOUCHER IN REQUEST BODY
{
"errors": [
{
"code": 400,
"message": "MATRIXX:POST_TOPUP_BALANCE",
"description": "52 | The AUTHORIZATION_AND_SETTLEMENT Request to Braintree has Failed: Invalid Payment Method Nonce QWEDRFRG"
}
]
}IF WE ARE PASSING INVALID PAYMENT Gateway ID REQUEST BODY
{
"errors": [
{
"code": 400,
"message": "MATRIXX:POST_TOPUP_BALANCE",
"description": "52 | No Payment Gateway with Id 3 has been configured"
}
]
}